<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>dbc put</title>
    <link rel="stylesheet" href="apiReference.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB TCL API Reference" />
    <link rel="up" href="tclapi.html" title="Chapter 1.  Berkeley DB Tcl APIs" />
    <link rel="prev" href="dbc_get.html" title="dbc get" />
    <link rel="next" href="env_close.html" title="env close" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 12.1.6.2</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center"><span xmlns="http://www.w3.org/1999/xhtml" class="emphasis"><em>dbc</em></span> put</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="dbc_get.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 1. 
                Berkeley DB Tcl APIs
        </th>
          <td width="20%" align="right"> <a accesskey="n" href="env_close.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="dbc_put"></a><span class="emphasis"><em>dbc</em></span> put</h2>
          </div>
        </div>
      </div>
      <pre class="programlisting">dbc put
	[-after]
	[-before]
	[-current]
	[-partial {doff dlen}]
	data

dbc put
	[-keyfirst]
	[-keylast]
	[-partial {doff dlen}]
	key data  </pre>
      <p>
         The <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span>
         command stores the specified key/data pair into the database.  One of
         the following options must be specified:
    </p>
      <div class="itemizedlist">
        <ul type="disc">
          <li>
            <p>
                 <span class="bold"><strong>-after</strong></span> 
            </p>
            <p>
                 In the case of the Btree and Hash access methods, insert the data
                 element as a duplicate element of the key to which the cursor refers.
                 The new element appears immediately after the current cursor position.
                 It is an error to specify <span class="bold"><strong>-after</strong></span> if
                 the underlying Btree or Hash database was not created with the
                 <span class="bold"><strong>-dup</strong></span> option. No key argument should
                 be specified.     
             </p>
            <p>
                 In the case of the Recno access method, it is an error to specify the
                 <span class="bold"><strong>-after</strong></span> option if the underlying Recno
                 database was not created with the <span class="bold"><strong>-renumber</strong></span> option.  If the <span class="bold"><strong>-renumber</strong></span> option was specified, a new key is
                 created, all records after the inserted item are automatically
                 renumbered, and the key of the new record is returned in the structure
                 to which the key argument refers. The initial value of the key
                 parameter is ignored. See <span class="bold"><strong>berkdb open</strong></span>
                 for more information.
            </p>
            <p>
                 In the case of the Queue access method, it is always an error to
                 specify <span class="bold"><strong>-after</strong></span>.
            </p>
            <p>
                 If the current cursor record has already been deleted, and the
                 underlying access method is Hash, <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> will throw a Tcl error. If the underlying
                 access method is Btree or Recno, the operation will succeed.
            </p>
          </li>
          <li>
            <p>
                  <span class="bold"><strong>-before</strong></span> 
            </p>
            <p>
                 In the case of the Btree and Hash access methods, insert the data
                 element as a duplicate element of the key to which the cursor refers.
                 The new element appears immediately before the current cursor
                 position. It is an error to specify <span class="bold"><strong>-before</strong></span> if the underlying Btree or Hash
                 database was not created with the <span class="bold"><strong>-dup</strong></span> option. No key argument should be
                 specified.     
            </p>
            <p>
                 In the case of the Recno access method, it is an error to specify
                 <span class="bold"><strong>-before</strong></span> if the underlying Recno
                 database was not created with the <span class="bold"><strong>-before</strong></span> option.  If the <span class="bold"><strong>-before</strong></span> option was specified, a new key is
                 created, the current record and all records after it are automatically
                 renumbered, and the key of the new record is returned in the structure
                 to which the key argument refers.  The initial value of the key
                 parameter is ignored. See <span class="bold"><strong>berkdb open</strong></span>
                 for more information.
            </p>
            <p>
                 In the case of the Queue access method, it is always an error to
                 specify <span class="bold"><strong>-before</strong></span>.
            </p>
            <p>
                 If the current cursor record has already been deleted and the
                 underlying access method is Hash, <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> will throw a Tcl error. If the underlying
                 access method is Btree or Recno, the operation will succeed.
            </p>
          </li>
          <li>
            <p>
                  <span class="bold"><strong>-current</strong></span> 
            </p>
            <p>
                 Overwrite the data of the key/data pair to which the cursor refers
                 with the specified data item.  No key argument should be specified.   
             </p>
            <p>
                 If the <span class="bold"><strong>-dupsort</strong></span> option was specified
                 to <span class="bold"><strong>berkdb open</strong></span> and the data item of
                 the key/data pair to which the cursor refers does not compare equally
                 to the data parameter, <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> will throw a Tcl error.
            </p>
            <p>
                 If the current cursor record has already been deleted and the
                 underlying access method is Hash, <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> will throw a Tcl error. If the underlying
                 access method is Btree, Queue, or Recno, the operation will succeed.
            </p>
          </li>
          <li>
            <p>
                  <span class="bold"><strong>-keyfirst</strong></span> 
            </p>
            <p>
                 In the case of the Btree and Hash access methods, insert the specified
                 key/data pair into the database.     
             </p>
            <p>
                 If the key already exists in the database, and the <span class="bold"><strong>-dupsort</strong></span> option was specified to <span class="bold"><strong>berkdb open</strong></span>, the inserted data item is added in
                 its sorted location.  If the key already exists in the database, and
                 the <span class="bold"><strong>-dupsort</strong></span> option was not
                 specified, the inserted data item is added as the first of the data
                 items for that key.
            </p>
            <p>
                 The <span class="bold"><strong>-keyfirst</strong></span> option may not be
                 specified to the Queue or Recno access methods.
            </p>
          </li>
          <li>
            <p>
                  <span class="bold"><strong>-keylast</strong></span> 
            </p>
            <p>
                 In the case of the Btree and Hash access methods, insert the specified
                 key/data pair into the database.     
             </p>
            <p>
                 If the key already exists in the database, and the <span class="bold"><strong>-dupsort</strong></span> option was specified to <span class="bold"><strong>berkdb open</strong></span>, the inserted data item is added in
                 its sorted location.  If the key already exists in the database, and
                 the <span class="bold"><strong>-dupsort</strong></span> option was not
                 specified, the inserted data item is added as the last of the data
                 items for that key.
            </p>
            <p>
                 The <span class="bold"><strong>-keylast</strong></span> option may not be
                 specified to the Queue or Recno access methods.
            </p>
          </li>
          <li>
            <p>
                  <span class="bold"><strong>-partial {doff dlen}</strong></span> 
            </p>
            <p>
                 The <span class="bold"><strong>dlen</strong></span> bytes starting <span class="bold"><strong>doff</strong></span> bytes from the beginning of the specified
                 key's data record are replaced by the data specified by the data and
                 size structure elements.  If <span class="bold"><strong>dlen</strong></span> is
                 smaller than the length of the supplied data, the record will grow; if
                 <span class="bold"><strong>dlen</strong></span> is larger than the length of the
                 supplied data, the record will shrink.  If the specified bytes do not
                 exist, the record will be extended using nul bytes as necessary, and
                 the <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> call
                 will succeed.
            </p>
            <p>
                 It is an error to attempt a partial put using the
                 <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> command
                 in a database that supports duplicate records. Partial puts in
                 databases supporting duplicate records must be done using a
                 <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> command.
            </p>
            <p>
                 It is an error to attempt a partial put with differing <span class="bold"><strong>dlen</strong></span> and supplied data length values in Queue
                 or Recno databases with fixed-length records.
            </p>
          </li>
        </ul>
      </div>
      <p>
         If a key is specified, and if the underlying database is a Queue or
         Recno database, the given key will be interpreted by Tcl as an
         integer.  For all other database types, the key is interpreted by Tcl
         as a byte array.
    </p>
      <p>
         If <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> fails
         for any reason, the state of the cursor will be unchanged. If
         <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> succeeds
         and an item is inserted into the database, the cursor is always
         positioned to refer to the newly inserted item.
    </p>
      <p>
         The <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span>
         command returns 0 on success, and in the case of error, a Tcl error is
         thrown.
    </p>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="dbc_get.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="tclapi.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="env_close.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top"><span class="emphasis"><em>dbc</em></span> get </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> <span class="emphasis"><em>env</em></span> close</td>
        </tr>
      </table>
    </div>
  </body>
</html>
